figma-metadata-extractor 1.0.2 → 1.0.4

package/README.md

@@ -10,8 +10,28 @@ npm install figma-metadata-extractor
 
 ## Quick Start
 
+### Get Metadata with Auto-Downloaded Images (LLM-Ready!)
+
 ```typescript
-import { getFigmaMetadata, downloadFigmaImages, downloadFigmaFrameImage } from 'figma-metadata-extractor';
+import { getFigmaMetadata } from 'figma-metadata-extractor';
+
+// Extract metadata AND automatically download image assets
+const metadata = await getFigmaMetadata(
+  'https://figma.com/file/ABC123/My-Design',
+  {
+    apiKey: 'your-figma-api-key',
+    outputFormat: 'object',
+    downloadImages: true,        // Auto-download image assets
+    localPath: './assets/images' // Where to save images
+  }
+);
+
+```
+
+### Get Metadata Only (No Downloads)
+
+```typescript
+import { getFigmaMetadata } from 'figma-metadata-extractor';
 
 // Extract metadata from a Figma file
 const metadata = await getFigmaMetadata(
@@ -77,9 +97,24 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
 - `useOAuth?: boolean` - Whether to use OAuth instead of API key
 - `outputFormat?: 'json' | 'yaml' | 'object'` - Output format (default: 'object')
 - `depth?: number` - Maximum depth to traverse the node tree
+- `downloadImages?: boolean` - Automatically download image assets and enrich metadata (default: false)
+- `localPath?: string` - Local path for downloaded images (required if downloadImages is true)
+- `imageFormat?: 'png' | 'svg'` - Image format for downloads (default: 'png')
+- `pngScale?: number` - Export scale for PNG images (default: 2)
 
 **Returns:** Promise<FigmaMetadataResult | string>
 
+When `downloadImages` is true, nodes with image assets will include a `downloadedImage` property:
+```typescript
+{
+  filePath: string;           // Absolute path
+  relativePath: string;       // Relative path for code
+  dimensions: { width, height };
+  markdown: string;           // ![name](path)
+  html: string;              // <img src="..." />
+}
+```
+
 ### `downloadFigmaImages(figmaUrl, nodes, options)`
 
 Downloads SVG and PNG images from a Figma file.

package/dist/index.cjs

@@ -1365,7 +1365,18 @@ function collapseSvgContainers(node, result, children) {
   return children;
 }
 async function getFigmaMetadata(figmaUrl, options = {}) {
-  const { apiKey, oauthToken, useOAuth = false, outputFormat = "object", depth } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    outputFormat = "object",
+    depth,
+    downloadImages = false,
+    localPath,
+    imageFormat = "png",
+    pngScale = 2,
+    useRelativePaths = true
+  } = options;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
   }
@@ -1399,11 +1410,33 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
     const { nodes, globalVars, ...metadata } = simplifiedDesign;
-    const result = {
+    let result = {
       metadata,
       nodes,
       globalVars
     };
+    if (downloadImages) {
+      if (!localPath) {
+        throw new Error("localPath is required when downloadImages is true");
+      }
+      Logger.log("Discovering and downloading image assets...");
+      const imageAssets = findImageAssets(nodes, globalVars);
+      Logger.log(`Found ${imageAssets.length} image assets to download`);
+      if (imageAssets.length > 0) {
+        const imageNodes = imageAssets.map((asset) => ({
+          nodeId: asset.id,
+          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+        }));
+        const downloadResults = await figmaService.downloadImages(
+          fileKey,
+          localPath,
+          imageNodes,
+          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+        );
+        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths);
+        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+      }
+    }
     if (outputFormat === "json") {
       return JSON.stringify(result, null, 2);
     } else if (outputFormat === "yaml") {
@@ -1497,6 +1530,68 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+function sanitizeFileName(name) {
+  return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function findImageAssets(nodes, globalVars) {
+  const images = [];
+  function traverse(node) {
+    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
+    if (isImageAsset) {
+      images.push(node);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      node.children.forEach(traverse);
+    }
+  }
+  nodes.forEach(traverse);
+  return images;
+}
+function hasImageFill(node, globalVars) {
+  if (!node.fills || typeof node.fills !== "string") {
+    return false;
+  }
+  const fillData = globalVars?.styles?.[node.fills];
+  if (!fillData || !Array.isArray(fillData)) {
+    return false;
+  }
+  return fillData.some((fill) => fill?.type === "IMAGE");
+}
+function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths = true) {
+  const imageMap = /* @__PURE__ */ new Map();
+  imageAssets.forEach((asset, index) => {
+    const result = downloadResults[index];
+    if (result) {
+      let pathForMarkup;
+      if (useRelativePaths === false) {
+        pathForMarkup = result.filePath;
+      } else if (typeof useRelativePaths === "string") {
+        pathForMarkup = result.filePath.replace(useRelativePaths, ".");
+      } else {
+        pathForMarkup = result.filePath.replace(process.cwd(), ".");
+      }
+      imageMap.set(asset.id, {
+        filePath: result.filePath,
+        relativePath: pathForMarkup,
+        dimensions: result.finalDimensions,
+        wasCropped: result.wasCropped,
+        markdown: `![${asset.name}](${pathForMarkup})`,
+        html: `<img src="${pathForMarkup}" alt="${asset.name}" width="${result.finalDimensions.width}" height="${result.finalDimensions.height}">`
+      });
+    }
+  });
+  function enrichNode(node) {
+    const enriched = { ...node };
+    if (imageMap.has(node.id)) {
+      enriched.downloadedImage = imageMap.get(node.id);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      enriched.children = node.children.map(enrichNode);
+    }
+    return enriched;
+  }
+  return nodes.map(enrichNode);
+}
 exports.allExtractors = allExtractors;
 exports.collapseSvgContainers = collapseSvgContainers;
 exports.componentExtractor = componentExtractor;

package/dist/index.js

@@ -1363,7 +1363,18 @@ function collapseSvgContainers(node, result, children) {
   return children;
 }
 async function getFigmaMetadata(figmaUrl, options = {}) {
-  const { apiKey, oauthToken, useOAuth = false, outputFormat = "object", depth } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    outputFormat = "object",
+    depth,
+    downloadImages = false,
+    localPath,
+    imageFormat = "png",
+    pngScale = 2,
+    useRelativePaths = true
+  } = options;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
   }
@@ -1397,11 +1408,33 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
     const { nodes, globalVars, ...metadata } = simplifiedDesign;
-    const result = {
+    let result = {
       metadata,
       nodes,
       globalVars
     };
+    if (downloadImages) {
+      if (!localPath) {
+        throw new Error("localPath is required when downloadImages is true");
+      }
+      Logger.log("Discovering and downloading image assets...");
+      const imageAssets = findImageAssets(nodes, globalVars);
+      Logger.log(`Found ${imageAssets.length} image assets to download`);
+      if (imageAssets.length > 0) {
+        const imageNodes = imageAssets.map((asset) => ({
+          nodeId: asset.id,
+          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+        }));
+        const downloadResults = await figmaService.downloadImages(
+          fileKey,
+          localPath,
+          imageNodes,
+          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+        );
+        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths);
+        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+      }
+    }
     if (outputFormat === "json") {
       return JSON.stringify(result, null, 2);
     } else if (outputFormat === "yaml") {
@@ -1495,6 +1528,68 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+function sanitizeFileName(name) {
+  return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function findImageAssets(nodes, globalVars) {
+  const images = [];
+  function traverse(node) {
+    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
+    if (isImageAsset) {
+      images.push(node);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      node.children.forEach(traverse);
+    }
+  }
+  nodes.forEach(traverse);
+  return images;
+}
+function hasImageFill(node, globalVars) {
+  if (!node.fills || typeof node.fills !== "string") {
+    return false;
+  }
+  const fillData = globalVars?.styles?.[node.fills];
+  if (!fillData || !Array.isArray(fillData)) {
+    return false;
+  }
+  return fillData.some((fill) => fill?.type === "IMAGE");
+}
+function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths = true) {
+  const imageMap = /* @__PURE__ */ new Map();
+  imageAssets.forEach((asset, index) => {
+    const result = downloadResults[index];
+    if (result) {
+      let pathForMarkup;
+      if (useRelativePaths === false) {
+        pathForMarkup = result.filePath;
+      } else if (typeof useRelativePaths === "string") {
+        pathForMarkup = result.filePath.replace(useRelativePaths, ".");
+      } else {
+        pathForMarkup = result.filePath.replace(process.cwd(), ".");
+      }
+      imageMap.set(asset.id, {
+        filePath: result.filePath,
+        relativePath: pathForMarkup,
+        dimensions: result.finalDimensions,
+        wasCropped: result.wasCropped,
+        markdown: `![${asset.name}](${pathForMarkup})`,
+        html: `<img src="${pathForMarkup}" alt="${asset.name}" width="${result.finalDimensions.width}" height="${result.finalDimensions.height}">`
+      });
+    }
+  });
+  function enrichNode(node) {
+    const enriched = { ...node };
+    if (imageMap.has(node.id)) {
+      enriched.downloadedImage = imageMap.get(node.id);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      enriched.children = node.children.map(enrichNode);
+    }
+    return enriched;
+  }
+  return nodes.map(enrichNode);
+}
 export {
   allExtractors,
   collapseSvgContainers,

package/dist/lib.d.ts

@@ -9,6 +9,21 @@ export interface FigmaMetadataOptions {
     outputFormat?: "json" | "yaml" | "object";
     /** Maximum depth to traverse the node tree */
     depth?: number;
+    /** Automatically download image assets and enrich metadata with file paths */
+    downloadImages?: boolean;
+    /** Local path for downloaded images (required if downloadImages is true) */
+    localPath?: string;
+    /** Image format for downloads (defaults to 'png') */
+    imageFormat?: 'png' | 'svg';
+    /** Export scale for PNG images (defaults to 2) */
+    pngScale?: number;
+    /**
+     * Use relative paths in downloadedImage properties instead of absolute paths.
+     * If true, paths will be relative to process.cwd().
+     * If a string, paths will be relative to that base path.
+     * Default: true
+     */
+    useRelativePaths?: boolean | string;
 }
 export interface FigmaImageOptions {
     /** Export scale for PNG images (defaults to 2) */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "figma-metadata-extractor",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "Extract metadata and download images from Figma files. A standalone library for accessing Figma design data and downloading frame images programmatically.",
     "type": "module",
     "main": "dist/index.cjs",